home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 033a / sage32.zip / MANUAL.DOC < prev    next >
Text File  |  1992-01-03  |  20KB  |  562 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                                                                 SAGE 3.2
  22.         ----------------------------------------------------------------
  23.                                                         Reference Manual
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.                                                          by Larry Antram
  44.                                            Megadyne Software Development
  45.                                                     Valencia, California
  46.  
  47.         SAGE 3.2 is not public domain software.
  48.  
  49.         SAGE 3.2 is copyright 1991-1992 by Megadyne Software
  50.         Development. All rights reserved.
  51.  
  52.         You are free to use, copy, and distribute this program if no fee
  53.         is charged for use, copying, or distribution and it is not
  54.         modified in any way.
  55.  
  56.         Megadyne Software Development disclaims all warranties, whether
  57.         express or implied, including without limitation any implied
  58.         warranties of merchantability, fitness for a particular purpose,
  59.         data integrity or protection, or functionality.
  60.  
  61.         If you find SAGE useful, a registration of $25 would be
  62.         appreciated. To those interested in programming, the C++ source
  63.         code is available for $99 to unregistered users, and $74 to
  64.         registered users.
  65.  
  66.         For more information, or if you have any questions or comments,
  67.         send them to Larry Antram at:
  68.  
  69.         Snail: Megadyne Software Development, 25144-A Steinbeck Avenue,
  70.                Valencia, California 91381-1215 USA
  71.  
  72.         Datel: Hidden BBS, +1 805/252-3683, 14.4K USR/HST, Sysop: Jim
  73.                Dunham
  74.  
  75.         SAGE and Megadyne are trademarks of Megadyne Software
  76.         Development.
  77.  
  78.         CONTENTS
  79.  
  80.         PART 1                                              INTRODUCTION
  81.  
  82.                 Description ........................................ 1.1
  83.                 Packing List ....................................... 1.2
  84.                 Requirements ....................................... 1.3
  85.                 Installation ....................................... 1.4
  86.                 Execution .......................................... 1.5
  87.                 Errorlevel ......................................... 1.6
  88.                 Index File ......................................... 1.7
  89.  
  90.         PART 2                                               DIGEST FILE
  91.  
  92.                 Overview ........................................... 2.1
  93.                 Capacity ........................................... 2.2
  94.                 Layout ............................................. 2.3
  95.                 Signature .......................................... 2.3
  96.                 Comment ............................................ 2.4
  97.                 Delimiter .......................................... 2.5
  98.                 Message ............................................ 2.6
  99.  
  100.         PART 3                                                STYLE FILE
  101.  
  102.                 Overview ........................................... 3.1
  103.                 Layout ............................................. 3.2
  104.                 Signature .......................................... 3.3
  105.                 Design ............................................. 3.4
  106.                 Macros ............................................. 3.5
  107.                 Macro Expansion .................................... 3.6
  108.                 Creating and Editing ............................... 3.7
  109.  
  110.         PART 4                                                 REFERENCE
  111.  
  112.                 Commands ........................................... 4.1
  113.                         ?, Show Help Screen ........................ 4.1
  114.                         i, Show License Information ................ 4.1
  115.                         x, Extract Message ......................... 4.1
  116.                         r, Rebuild Index ........................... 4.1
  117.  
  118.                 Options ............................................ 4.2
  119.                         -e, Log Errors ............................. 4.2
  120.                         -q, Quiet Mode ............................. 4.2
  121.  
  122.                 Style Macros ....................................... 4.3
  123.                         @BODY@ ..................................... 4.3
  124.                         @FIRST_LINE@ ............................... 4.3
  125.                         @BODY_MINUS_FIRST_LINE@ .................... 4.3
  126.  
  127.         PART 1
  128.         INTRODUCTION
  129.  
  130.         1.1 Description
  131.  
  132.                 SAGE is a utility that manages collections of quotes (or
  133.                 other items).  Upon command it will randomly select and
  134.                 present one.
  135.  
  136.                 SAGE can be is useful to:
  137.  
  138.                     - BBS System Operators: SAGE will generate logoff,
  139.                       news, or bulletins for your bbs.  SAGE is designed
  140.                       so it can be used with any bbs software.
  141.  
  142.                     - Users with Hard Drives: Put SAGE in your
  143.                       autoexec.bat file, and it will generate a
  144.                       different quote every time you start your computer.
  145.  
  146.         1.2 Packing List
  147.  
  148.                 SAGE is distributed in compressed archive form.
  149.  
  150.                 The contents include the following files:
  151.  
  152.                     SAGE.EXE     - executable program
  153.                     MANUAL.DOC   - reference manual (this document)
  154.                     WHATSNEW.DOC - lists changes between versions
  155.                     SAMPLE.DIG   - sample digest file of quotes
  156.                     ANSI1.STY    - sample ANSI graphics style file
  157.                     ANSI2.STY    - sample ANSI graphics style file
  158.                     ANSI3.STY    - sample ANSI graphics style file
  159.                     ANSI4.STY    - sample ANSI graphics style file
  160.                     PCB1.STY     - sample PCBoard codes style file
  161.                     PCB2.STY     - sample PCBoard codes style file
  162.                     PCB3.STY     - sample PCBoard codes style file
  163.                     PCB4.STY     - sample PCBoard codes style file
  164.                     TEXT1.STY    - sample text style file
  165.                     TEXT2.STY    - sample text style file
  166.                     TEXT3.STY    - sample text style file
  167.                     TEXT4.STY    - sample text style file
  168.  
  169.                 All files should have the exact same date and time
  170.                 stamp.
  171.  
  172.         1.3 Requirements
  173.  
  174.                 SAGE requires an IBM-PC computer running PC-DOS 3.3 or
  175.                 greater operating system, or compatible.
  176.  
  177.         1.4 Installation
  178.  
  179.                 Installing SAGE onto your hard disk is very simple.
  180.  
  181.                         1. create a subdirectory named \SAGE
  182.  
  183.                         2. copy all of the files into it
  184.  
  185.                 Consult your DOS operations manual for the exact
  186.                 commands.
  187.  
  188.         1.5 Execution
  189.  
  190.                 The following is a quick summary of some commands that
  191.                 you can type at the DOS prompt.
  192.  
  193.                 To see the SAGE help screen:     sage ?
  194.  
  195.                 To make SAGE generate a quote:   sage x sample
  196.                 If you have ANSI.SYS installed:  sage x sample ansi1.sty
  197.  
  198.                 To send the quote to a file:     sage x sample q.txt
  199.                 Or to make an ANSI file:         sage x sample ansi1 q.ans
  200.                 Or to make a file for PCBoard:
  201.                                  sage x sample pcb1.sty \pcb\gen\script0
  202.  
  203.                 To see the SAGE license info:    sage i
  204.  
  205.         1.6 Errorlevel
  206.  
  207.                 SAGE will exit with an errorlevel of 0 on success.  It
  208.                 will return an errorlevel of 1 if an error occurs.  This
  209.                 value can be examined in a batch file using the DOS
  210.                 errorlevel variable.
  211.  
  212.         1.7 Index File
  213.  
  214.                 SAGE will generate an index for any digest it uses. This
  215.                 index is used to quickly retrieve quotes.
  216.  
  217.                 If the index is missing SAGE will automatically build a
  218.                 new one.
  219.  
  220.                 If you modify a digest, SAGE will automatically sense
  221.                 this has happened and rebuild the index.
  222.  
  223.                 If you wish to force an index to be rebuilt, then just
  224.                 delete it.  The next time SAGE uses the digest it will
  225.                 notice the index is missing, and make a new one.
  226.  
  227.                 An index file will have the same name as the digest,
  228.                 except instead of .DIG it will have an .IDX extension.
  229.  
  230.         PART 2
  231.         DIGEST FILE
  232.  
  233.         2.1 Overview
  234.  
  235.                 Digest files are plain ASCII text files that hold a
  236.                 collection of messages, which are typically quotes.
  237.                 Digest files end with the .DIG extension.  You can use
  238.                 any text editor to view or modify them.
  239.  
  240.         2.2 Capacity
  241.  
  242.                 Digest files can be up to 4 gigabytes in size.
  243.  
  244.         2.3 Layout
  245.  
  246.                 Each line is delimited with a carriage return / line
  247.                 feed combination.
  248.  
  249.                 The specific layout of the file is as follows:
  250.  
  251.                         +-------------+
  252.                     (1) | Signature   |
  253.                         +-------------+
  254.                     (2) | Comment     |
  255.                         +-------------+
  256.                     (3) | Delimiter   |
  257.                         +-------------+
  258.                     (4) | Message     |
  259.                         +-------------+
  260.                     (5) | Delimiter   |
  261.                         +-------------+
  262.  
  263.                 4 and 5 can be repeated as many times as is necessary.
  264.  
  265.                 Each of the above is explained in more detail below.
  266.  
  267.  
  268.         2.3 Signature
  269.  
  270.                 The first line of a digest must consist solely of a
  271.                 predefined signature.
  272.  
  273.                 The exact format of the signature is as follows (where
  274.                 \r represents a carriage return and \n represents a line
  275.                 feed:
  276.  
  277.                 SAGE_DIGEST\r\n
  278.  
  279.         2.4 Comment
  280.  
  281.                 The area between the signature and first delimiter is
  282.                 considered the comment area.  You can type any notes or
  283.                 comments there.
  284.  
  285.                 The data in this area can be anything, as long as it
  286.                 doesn't contain the delimiter mark.  (The delimiter mark
  287.                 is explained in more detail below).
  288.  
  289.                 The comment area can be any length, as long as the
  290.                 entire digest remains smaller than 4 gigabytes.
  291.  
  292.                 The comment area is optional; it does not have to be
  293.                 present.
  294.  
  295.         2.5 Delimiter
  296.  
  297.                 A "delimiter" is used to separate items in the digest.
  298.  
  299.                 This term can be used in two different contexts.
  300.  
  301.                 - the delimiter mark
  302.                 - the delimiter line
  303.  
  304.                 The delimiter mark, by default, is %% ( 2 percent
  305.                 characters side by side ).
  306.  
  307.                 Any line that contains the delimiter mark is considered
  308.                 a delimiter line.
  309.  
  310.                 Anything which is on the delimiter line, besides the
  311.                 delimiter mark, is ignored.
  312.  
  313.         2.6 Message
  314.  
  315.                 The area between delimiters is the message area.
  316.  
  317.                 The message area can contain anything, except the
  318.                 delimiter mark.
  319.  
  320.                 Each message can be any length, as long as the entire
  321.                 digest remains smaller than 4 gigabytes.
  322.  
  323.         PART 3
  324.         STYLE FILE
  325.  
  326.         3.1 Overview
  327.  
  328.                 Style files are used to format the output created by
  329.                 SAGE.  You can surround it with text, ANSI graphics,
  330.                 PCBoard control codes, or just about anything else you
  331.                 can think of.
  332.  
  333.                 Several example style files are provided with SAGE.
  334.                 Style files end with the .STY extension.
  335.  
  336.         3.2 Layout
  337.  
  338.                 Each line is delimited with a carriage return / line
  339.                 feed combination.
  340.  
  341.                 The specific layout of the file is as follows:
  342.  
  343.                         +-------------+
  344.                     (1) | Signature   |
  345.                         +-------------+
  346.                     (2) | Design      |
  347.                         +-------------+
  348.  
  349.                 Each of the above is explained in more detail below.
  350.  
  351.         3.3 Signature
  352.  
  353.                 The first line of a style file must consist solely of a
  354.                 predefined signature.
  355.  
  356.                 The exact format of the signature is as follows (where
  357.                 \r represents a carriage return and \n represents a line
  358.                 feed:
  359.  
  360.                 SAGE_STYLE\r\n
  361.  
  362.         3.4 Design
  363.  
  364.                 The area between the signature and end of file is the
  365.                 design area.  It can consist of just about anything.
  366.                 Typically it is text, or text with control codes (ie:
  367.                 ANSI,PCBoard-Codes,etc.)
  368.  
  369.                 The design area can be any size.
  370.  
  371.         3.5 Macros
  372.  
  373.                 When creating a style file, you place macros into the
  374.                 design area.  These macros tell SAGE where to put the
  375.                 quote.
  376.  
  377.                 Here is a list of the macros:
  378.  
  379.                         @BODY@
  380.                         @FIRST_LINE@
  381.                         @BODY_MINUS_FIRST_LINE@
  382.  
  383.                 The @BODY@ macro will be overwritten with the entire
  384.                 quote.
  385.  
  386.                 The @FIRST_LINE@ macro will be overwritten with the
  387.                 first line of the quote.
  388.  
  389.                 The @BODY_MINUS_FIRST_LINE@ macro will be overwritten
  390.                 with the entire quote, minus the first line.
  391.  
  392.         3.6 Macro Expansion
  393.  
  394.                 SAGE will expand the macros by overwriting them with the
  395.                 quote data.  If the quote data is shorter than the macro
  396.                 itself, then the rest of the macro is replaced with
  397.                 space characters.
  398.  
  399.                 If you intend to "frame" a quote, then you should make
  400.                 sure you have allowed enough space to completely contain
  401.                 the longest line of any quote, between the start of the
  402.                 macro and the start of any significant data on the right
  403.                 side of the design.
  404.  
  405.                 The file ANSI4.STY is an example of how to do this.
  406.                 Notice the space to the right of the @BODY@ macro.
  407.  
  408.         3.7  Creating and Editing
  409.  
  410.                 You can make style files easily, with a program such as
  411.                 TheDraw, PCBDraw, or even a text editor such as QEdit.
  412.                 Just place the style macros where you want them to be
  413.                 overwritten in your picture.
  414.  
  415.                 If you use drawing program, it is recommended that you
  416.                 add the style signature line, with a text editor, when
  417.                 you are done.  Otherwise, you may need to edit the style
  418.                 file in order to remove any extraneous control codes
  419.                 from the signature line.
  420.  
  421.                 Remember, the signature line must remain exactly as
  422.                 outlined above.  It can't be any different.
  423.  
  424.         PART 4
  425.         REFERENCE
  426.  
  427.         4.1 Commands
  428.  
  429.         The following is a listing of the commands, their usage, and the
  430.         options that can be used with them.
  431.  
  432.         ?, Show Help Screen
  433.  
  434.                 Syntax: sage ?
  435.  
  436.                 This commands prints the help screen to the standard
  437.                 output device, which (unless redirected) is the monitor.
  438.  
  439.                 Example: sage ?
  440.  
  441.         i, Show License Information
  442.  
  443.                 Syntax: sage i
  444.  
  445.                 This command prints licensing information to the standard
  446.                 output device.  It also lists how to contact the author.
  447.  
  448.                 Example: sage i
  449.  
  450.         x, Extract Message
  451.  
  452.                 Syntax: sage x [options] <digest_file> [style_file]
  453.                         [output_file]
  454.  
  455.                 This will extract an item from a digest, and print it to
  456.                 the standard output.
  457.  
  458.                 Other information besides the message is included.  This
  459.                 includes a copyright notice, the number of items in the
  460.                 digest, which item number was selected, etc.
  461.  
  462.                 Example: sage x sample.dig
  463.                 Example: sage x sample.dig > output.txt
  464.  
  465.                 An alternate, and perhaps more desirable, method is to
  466.                 use an output file.  It can be specified on the command
  467.                 line.
  468.  
  469.                 Example: sage x sample.dig output.txt
  470.  
  471.                 You can also use a style file to format how the output
  472.                 will appear.
  473.  
  474.                 Example: sage x sample.dig ansi1.sty
  475.                 Example: sage x sample.dig ansi1.sty output.ans
  476.  
  477.         r, Rebuild Index
  478.  
  479.                 Syntax: sage r [options] <digest_file>
  480.  
  481.                 This command will force the reconstruction of an index
  482.                 file.
  483.  
  484.                 Example: sage r sample.dig
  485.  
  486.                 An alternate method is to just delete the index file.
  487.  
  488.                 Example: del sample.idx
  489.  
  490.         4.2 Options
  491.  
  492.         -e, Log Errors
  493.  
  494.                 This option will report any errors that occur to the
  495.                 file sage.err.
  496.  
  497.                 This option can be used with the x and r commands.
  498.  
  499.                 Examples: sage x -e sample.dig quote.txt
  500.                           sage r -e sample.dig
  501.  
  502.         -q, Quiet Mode
  503.  
  504.                 The -q option will force SAGE into the "quiet" mode.
  505.  
  506.                 This keeps SAGE from reporting extra information to the
  507.                 screen.
  508.  
  509.                 For example, in quiet mode, SAGE does not report the
  510.                 number of messages in the digest, the actual message
  511.                 number selected, nor place a > character before any
  512.                 message that is extracted to the screen.
  513.  
  514.                 This option can be used with the x and r commands.
  515.  
  516.                 Examples: sage x -q sample.dig
  517.                           sage r -q sample.dig
  518.  
  519.         4.3 Style Macros
  520.  
  521.         @BODY@
  522.  
  523.                 SAGE will overwrite this macro with the entire body of the
  524.                 message.  The line that contains this macro, is repeated
  525.                 for the length of the quote.
  526.  
  527.         @FIRST_LINE@
  528.  
  529.                 SAGE will overwrite this macro with the first line of the
  530.                 quote.
  531.  
  532.         @BODY_MINUS_FIRST_LINE@
  533.  
  534.                 This is an alternate to the @BODY@ macro.  It is the
  535.                 same, except the first line is omitted.
  536.  
  537.         APPENDIX A
  538.         COMMENTS
  539.  
  540.         If you:
  541.  
  542.                 - have been waiting for a program to appear, but it just
  543.                   never happens
  544.  
  545.                 - need more information or have a question about this
  546.                   program
  547.  
  548.                 - have any comments, suggestions, or requests
  549.  
  550.         Then drop me a note.  I'm a pretty good at creating applications
  551.         with C and C++ under DOS, GEM, and Windows (and hopefully OS/2
  552.         soon).
  553.  
  554.         Address to Larry Antram at:
  555.  
  556.                 Snail: Megadyne Software Development, 25144-A Steinbeck
  557.                        Avenue, Valencia, California 91381-1215 USA
  558.  
  559.                 Datel: Hidden BBS, +1 805/252-3683, 14.4K USR/HST
  560.  
  561.  
  562.